Localizing WS-AppServer Messages

This topic describes the process to localize the messages generated by WS-AppServer.

Applications that are developed and deployed using WS-AppServer are equipped with the functionality of reporting the messages to the end-users in their local languages. Currently, WS-AppServer supports localizing messages while using the following classes and methods:

• BsfConstraintViolationException
• BsfApplicationRuntimeException
• ConstraintEvent.addError
• AccessEvent.setAccess
• ValuesEvent.addValue

1. Create a message definition file (XML document) that would contain the required messages. A sample is shown below:

   <MessageBundle id="mycomp.myapp.LocalizedMessages">
       <Message id="CustomerDoesNotExist">
           <MessageText>Customer {0} does not exist</MessageText>
           <Description>The specified customer does not exist, so the reference is invalid.</Description>
           <Annotations>
               <DocumentationURL/>
           </Annotations>
       </Message>
       <Message id="ValueInRange">
           <MessageText>The specified value must be between {0} and {1}</MessageText>
           <Description>To specify that a value is out of range</Description>
           <Annotations>
               <DocumentationURL/>
           </Annotations>
       </Message>
   </MessageBundle>
   

   Note: Ensure the following while creating the message definition file:

   • The name of the file must be of the following format: <id of the localization bundle>#MessageBundle#.xml (which is mycomp.myapp.LocalizedMessages#MessageBundle#.xml in the sample above). After the file is synchronized and published, the content is published to <Process_Platform_Installation_Directory>\localization folder as mycomp.myapp.LocalizedMessages.xml file
   • To retrieve the messages at runtime, the message definition file must be located in <Process_Platform_Installation_Directory>\localization. The default messages are located in <Process_Platform_Installation_Directory>\localization\mycomp.myapp.LocalizedMessages.xml.
   • For a specific locale, the file name has a locale suffix, such as
     _fr_CA for French in Canada. Thus, the file location for this locale would be <Process_Platform_Installation_Directory>\localization\mycomp.myapp.LocalizedMessages_fr_CA.xml.The actual locale for a user ideally depends on the browser's locale settings. However, it is possible to define a default locale setting (com.eibus.defaultLocale=nl), while installing Process Platform. This is stored as a property in wcp.properties file. If the locale settings are set to the default value, then the required message file would be mycomp.myapp.LocalizedMessages_nl.xml.
   • Do not include the 'Description' and 'Annotation' fields in the locale-specific file.
2. Generate the Java class from the message definition file, using a command similar to the following:

   C:\>java com.eibus.tools.internal.MessageGenerator
   Usage: MessageGenerator <Messages Definitions Filename> <Fully Qualified Class Name> [<Target Directory>]
    
   Usage example: java com.eibus.tools.internal.MessageGenerator D:\Cordys\localization\mycomp.myapp.LocalizedMessages.xml mycomp.myapp.MessageBundle D:\Cordys 
    
   The MessageBundle.java will be created in the directory 'D:\Cordys'

   The following output is derived.

   package com.mycomp.myapp;
    
   import com.eibus.localization.message.Message;
   import com.eibus.localization.message.MessageSet;
    
   /**
    * This code is generated by running
    * com.eibus.localization.message.MessageGenerator.
    * 
    * Generated by :user Input file :mycomp.myapp.LocalizedMessages.xml Generated
    * at :Fri Mar 10 15:01:33 CET 2006
    */
    
   public class LocalizedMessages {
       public static final MessageSet MESSAGE_SET = MessageSet
               .getMessageSet("mycomp.myapp.LocalizedMessages");
    
       /** Customer {0} does not exist */
       public static final Message CUSTOMER_DOES_NOT_EXIST = MESSAGE_SET
               .getMessage("CustomerDoesNotExist");
    
       /** The specified value must be between {0} and {1} */
       public static final Message VALUE_IN_RANGE = MESSAGE_SET
               .getMessage("ValueInRange");
    
   }
    

   Note: Java class needs to be generated only from the 'base' message definition file and not from the language-specific definitions.

3. In the application code, use this generated code as shown in the following sample:

   /**
    * Constraint handler for CustomerID.
    */
   public void onConstraint_CustomerID(AttributeConstraintEvent constrEvent)
   {
   // check the available Customers whether the Customer exists
   // the new CustomerID is passed via the context
   String customerID = (String)constrEvent.getValue();
   if ( Customers.getCustomersObject(customerID) == null )
   {
   constrEvent.addError(this, ATTR_CustomerID,
       LocalizedMessages. CUSTOMER_DOES_NOT_EXIST,
       new Object[]{customerID});
   // the traditional way is
   // constrEvent.addError(this, ATTR_CustomerID,
   // "Customer " + customerID + " does not exist");
   }
   }

   Note: The message (com.eibus.localization.message.Message) implements the interface ILocalizalbleString (com.eibus.localization.ILocalizableString). You can define parameters in the message (messageParams). However, these parameters are substituted at the moment the actual message is constructed.
   
   WS-AppServer messages are localized to a particular language.